Significant Updates to CloudTrail Events for AWS IAM Identity Center

Learn About Amazon VGT2 Learning Manager Chanci Turner

In response to user feedback, we have adjusted the effective date for the forthcoming changes to CloudTrail events from January 13, 2025, to July 14, 2025. It is important to note that these modifications will specifically impact IAM Identity Center CloudTrail events.

AWS is refining CloudTrail events for AWS IAM Identity Center, retaining only the crucial fields required for operations like auditing and incident response. This refinement aims to streamline user identification in IAM Identity Center CloudTrail events, addressing feedback from our customers. Furthermore, it enhances the relationship between users in the IAM Identity Center directory and external directory services, such as Okta Universal Directory or Microsoft Active Directory. Importantly, these updates will not influence CloudTrail events from other AWS services.

Starting July 14, 2025, IAM Identity Center will cease to emit the userName and principalId fields within the user identity element of CloudTrail events. These fields will no longer be included when users sign in to IAM Identity Center, utilize the AWS access portal, or access AWS accounts via the AWS CLI. Instead, IAM Identity Center will provide the userId and identityStoreArn fields to replace the userName and principalId fields, simplifying user identification. Additionally, IAM Identity Center CloudTrail events will now indicate IdentityCenterUser as the identity type instead of Unknown, offering a clear user identifier. Furthermore, IAM Identity Center will no longer display the value of a group’s displayName in CloudTrail events when creating or updating a group. For authorized workflows, group attributes such as displayName can still be accessed through the Identity Store DescribeGroup API operation.

We highly recommend updating any workflows that process userName, principalId, userIdentity type, or group displayName fields in CloudTrail events for IAM Identity Center prior to the changes taking effect on July 14, 2025. This blog offers guidance on making those necessary updates.

Preparing Your Workflows for Changes to IAM Identity Center User Identification in CloudTrail

To enhance user identification, IAM Identity Center will modify the user identity element in its CloudTrail events. Based on these changes, you can adjust your workflows to connect CloudTrail events to specific users, link users with their external directories, and monitor user activity throughout the same session. An updated user identity element for a sample CloudTrail event is included at the end of this section.

IAM Identity Center will change the userIdentity type for CloudTrail events generated during user sign-ins, AWS access portal use, and AWS account access via the AWS CLI. For authenticated users, the userIdentity type will shift from Unknown to IdentityCenterUser. Unauthenticated users will still have their identity type listed as Unknown. We advise updating your workflows to accommodate both of these values.

To identify the user associated with a CloudTrail event, IAM Identity Center will now emit userId and identityStoreArn fields to replace the userName and principalId fields. The userId serves as a unique and immutable identifier assigned to each user in the Identity Store, referenced by the identityStoreArn. These new fields will significantly improve user identification and action tracking in CloudTrail, appearing in entries where the userIdentity type is IdentityCenterUser. For more information on the user identity element with the new fields, as well as the describe-user CLI command for retrieving user attributes using the user ID and Identity Store ARN, please refer to the Identifying the user and session in IAM Identity Center user-initiated CloudTrail events section of the IAM Identity Center User Guide.

In addition to other user attributes, you can utilize the describe-user CLI command to obtain the external ID tied to a user in the Identity Store. This external ID allows you to associate Identity Store users with their external directories. However, note that IAM Identity Center does not emit an external ID in CloudTrail; access to the Identity Store is required to retrieve an external ID using the userId and identityStoreArn fields in CloudTrail.

If you have access to CloudTrail events but lack access to the Identity Store, you can still use the UserName field under the additionalEventData element to correlate users with their external directories. This field represents the username utilized during authentication or federation when signing into IAM Identity Center. For further details, see the Correlating users between IAM Identity Center and external directories section of the IAM Identity Center User Guide.

Notes:

• When the identity source is the AWS Directory Service, the UserName value logged in the additionalEventData element corresponds to the username entered during authentication. For instance, if a user has the username anyuser@company.com, they can authenticate using anyuser, anyuser@company.com, or company.comanyuser, and the entered value will be emitted in CloudTrail respectively.
• In cases of sign-in failure due to incorrect username input, IAM Identity Center logs the UserName field in its CloudTrail event as HIDDEN_DUE_TO_SECURITY_REASONS. This is to protect sensitive information that could potentially be contained in the username input.

To monitor user activity throughout the same session, IAM Identity Center will introduce the credentialId field in CloudTrail events for user actions in the AWS access portal or AWS CLI. The credentialId field includes the AWS access portal session ID for a user, facilitating the tracking of user actions throughout their session.

The following table provides a sample CloudTrail event showcasing the fields, highlighted in yellow, that will be altered on July 14, 2025. IAM Identity Center recently began emitting userId, identityStoreArn, credentialId, and UserName in additional event data for its CloudTrail events, meaning these fields are considered existing.

Before the Upcoming Changes:

{
  "eventName": "CredentialChallenge",
  "eventSource": "signin.amazonaws.com",
  "userIdentity": {
    "type": "Unknown",
    "userName": "anyuser",
    "accountId": "123456789012",
    "principalId": "123456789012",
    "onBehalfOf": {
      "userId": "a11111-1111-1111-11a1-111aa111aa11",
      "identityStoreArn": "arn:aws:identitystore::111111111:identitystore/d-111111a1a"
    },
    "credentialId": "1111a111111111a1a11111a1a[…]"
  },
  "additionalEventData": {
      "CredentialType": "PASSWORD",
      "UserName": "anyuser"
  }
}

After the Upcoming Changes:

{
  "eventName": "CredentialChallenge",
  "eventSource": "signin.amazonaws.com",
  "userIdentity": {
    "type": "IdentityCenterUser",
    "accountId": "123456789012",
    "onBehalfOf": {
      "userId": "a11111-1111-1111-11a1-111aa111aa11",
      "identityStoreArn": "arn:aws:identitystore::111111111:identitystore/d-111111a1a"
    },
    "credentialId": "1111a111111111a1a11111a1a[…]"
  },
  "additionalEventData": {
      "CredentialType": "PASSWORD",
      "UserName": "anyuser"
  }
}

Preparing Your Workflows for Upcoming Changes to IAM Identity Center Group Management Events in CloudTrail

As you navigate these updates, it is essential to ensure your workflows are aligned with the new structures. Many resources are available to assist with this transition, including Career Contessa for career insights and SHRM for authoritative information on recruitment strategies. For further guidance on development opportunities within Amazon, visit Amazon Learning Development.